Common Workflows
How DecisionNode fits into your day-to-day development.
Search, decide, code
The basic loop: check what's already been decided, then code.
1. Search before you start
Before working on something, check if there are existing conventions:
decide search "how do we handle error logging?"
If the MCP server is connected, your AI does this automatically — the agent behavior setting controls how aggressively.
2. Record decisions as you go
When you agree on an approach, record it — interactively or in one command:
decide add # or inline: decide add -s UI -d "Use Tailwind" -r "Consistent tokens"
Or the AI calls add_decision through MCP. If a similar decision already exists, you'll be warned before it's saved.
3. Code
The next time you or a different AI session works in this area, the decisions will be there. No need to re-explain conventions.
New AI sessions
Decisions persist across sessions. When you start a new AI chat, the AI searches DecisionNode before writing code (if the MCP server is connected). It picks up all existing conventions without you having to repeat anything.
With agent behavior set to strict (default), the AI is instructed to search before every code change. On relaxed, it searches only when it thinks it's relevant. See agent behavior.
Global decisions
Some decisions apply across all your projects — things like "always use TypeScript strict mode" or "never commit .env files":
decide add --global
Global decisions are automatically included in search results for every project. If a project decision conflicts with a global one, the project decision takes priority. See global decisions in the CLI reference.
Deprecating decisions
When a convention is no longer relevant, deprecate it instead of deleting. Deprecated decisions are hidden from search but you can bring them back if you change your mind:
# Hide from search decide deprecate ui-015 # Bring it back decide activate ui-015
Deprecated decisions still show up in decide list (marked with ⚠️). The embedding is preserved, so re-activating is instant. See lifecycle.
Moving decisions between projects
Export from one project and import into another:
# Export — saves to a file you choose cd old-project decide export json > ~/decisions.json # Import — point to that file from another project cd new-project decide init decide import ~/decisions.json
decide export prints to the terminal — the > redirects it into a file at the path you specify. Imported decisions are automatically embedded. Use --global on either command to export/import global decisions.
Reviewing history
Every add, update, deprecation, activation, and delete is logged — along with which tool made the change. MCP clients are identified by name (e.g. claude-code, cursor) so you can see exactly where each change came from.
# View recent activity decide history # Filter by source decide history --filter mcp decide history --filter cli
Checking embedding health
If you've been adding decisions without an API key, or if embedding failed for some reason, decisions won't be searchable. Check and fix:
# See which decisions are missing embeddings decide check # Generate embeddings for anything that's missing decide embed # Clean up orphaned vectors from deleted decisions decide clean